Publishing an e-book

Now that we’ve seen how to create a simple HTML report using R Markdown and display it online, let’s build upon those skills and see how to publish an electronic book (“e-book”) so that it can be shared with and viewed by others. To do so, we’ll make use of the {bookdown} package, which is what Mark uses for his lab guide. You can see many other examples of different books written with {bookdown} here.

Task: If you haven’t done so already, install the {bookdown} package. Load it when done.

## install bookdown if necessary
## install.packages("bookdown")

## load bookdown
library("bookdown")

Create a new repo

Task: Navigate to GitHub and create a new public repo called book-demo. Add a README.md file and an R .gitignore file as well (you can skip a license file). CLick the green Create repository button when you’re ready.

Task: Click on the Settings button in the upper right.

Task: Click on the Pages button on the left side.

Task: Click on the None button under the Branch heading and swith it to main.

Task: Click on the / (root) button under the Branch heading and swith it to /docs.

Task: When you’re ready, click on the Save button.

Success: Your repo is now set to use GitHub Pages for displaying HTML files.

Create an RStudio project

Task: Create a new project in RStudio from the book-demo repo you just created.

Task: Create another project in RStudio but this time select the option for New Directory.

Task: From the Project Type window, select “Book project using bookdown”.

Task: Set the directory name and location to anything you’d like (eg, tmp). This will be a temporary folder/directory to hold a few files.

Task: Select bs4_book from the dropdown menu for HTML book format.

Task: Check the box for “Open in a new session” and click the Create Project button.

Task: Navigate to the temporary project/folder/directory you create above and move all of the files except the .Rproj file to the folder/directory where your book-demo project lives.

Success: You now have a template for creating and publishing an HTML e-book!

Task: Click on the Addins button at the top of your RStudio window and select “Preview Book” under “BOOKDOWN”.

Tip: You can also type bookdown:::serve_book() at the command prompt to preview your book.

Success: You can now see a preview of your book in the Viewer pane!


Editing your book


Viewing your document

Now that we’ve pushed our basic HTML report to GitHub, we should be able to view it online.

Task: Navigate back your book-demo repo on GitHub and you’ll see the /docs folder containing the various HTML and other associated files.

Tip: Recall that GitHub cannot render HTML files in a normal repo, but you can view your book by navigating to https://USERNAME.github.io/book-demo/ where USERNAME is your GitHub username.

Success: You now have an online book that you can update by making changes in your RStudio project and pushing them to GitHub.

Tip: You can add a link to your newly rendered document by edited the main page of your repo.

Task: Click on the small gear icon in the upper right, which will bring up a window to edit some aspects of your repo.

Task: In the Website field, type or copy/paste the link to your rendered site, which should be https://USERNAME.github.io/book-demo/ where USERNAME is your GitHub username. Click on the green Save changes button when you’re done.

Success: Your repo has now been updated to include a direct link to your properly rendered HTML report.